<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Hotkey</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link href="../css/default.css" rel="stylesheet" type="text/css">
</head>
<body>

<h1>Hotkey</h1>

<p>在脚本运行时创建, 修改, 启用或禁用热键.</p>

<pre class="Syntax">Hotkey, KeyName [, Label, Options]
Hotkey, IfWinActive/Exist [, WinTitle, WinText]
Hotkey, If, Expression</pre>
<h3>参数</h3>
<table class="info">
  <tr>
    <td width="15%">KeyName</td>
    <td width="85%"><p>热键的触发键的名称, 包括任何 <a href="../Hotkeys.htm#symbols">修饰符</a>. 例如, 指定 #c 来触发 Win+C 热键.</p>
    <p>如果 <em>KeyName</em> 是一个现有的热键, 那么原来的热键将被此命令的其他参数值更新.</p>
    <p><em>KeyName</em> 也可以是现有的热键标签的名称 (即双冒号标签), 这样使得原来的热键被此命令的其他参数值更新.</p>
    <p>当指定一个 <em>现有的</em> 热键时, <em>KeyName</em> 是不区分大小写的. 但是, 按键名称必须和现有的热键拼写相同 (即 这种情况下 Esc 与 Escape 是不同的). 并且, <a href="../Hotkeys.htm#Symbols">修饰符</a> 的顺序例如 ^!+# 是无关紧要的.</p>
    <p><a href="#IfWin">当前的 IfWin 设置</a> 决定了 Hotkey 命令将操作热键的哪个 <a href="#variant">变体</a>. 如果此变体还不存在, 它将被创建.</p>
    <p>当首次创建一个热键时 -- 通过 Hotkey 命令或脚本中的 <a href="../Hotkeys.htm">双冒号标签</a> -- 其键名以及修饰符的顺序成为此热键的固定名称, 像 <a href="../Variables.htm#ThisHotkey">A_ThisHotkey</a> 包含的那样. 即使之后 Hotkey 命令使用不同的修饰符顺序操作此热键, 其名称也不会改变.</p></td>
  </tr>
  <tr>
    <td>Label</td>
    <td><p>热键按下时, 将被执行 (作为一个新 <a href="../misc/Threads.htm">线程</a>) 的标签的名称. 可以使用普通标签和 <a href="../Hotkeys.htm">热键</a>/<a href="../Hotstrings.htm">热字串</a> 标签. 不要包含后面的冒号. 如果使用动态的 <em>Label</em> (例如 %VarContainingLabelName%), 请首先调用 <a href="../Functions.htm#IsLabel">IsLabel(VarContainingLabelName)</a> 来检查此标签是否存在.</p>
      <p>如果 <em>KeyName</em> 为现有的热键, 此参数可以留空, 此时其标签不会发生变化. 这在仅需要修改热键的 <em>Options</em> 时有用.</p>
      <p><strong>如果指定了标签但热键之前已经使用此命令禁用了, 那么热键将保持禁用状态. 要启用它, 在 <em>Options</em> 包含 ON.</strong></p>
      <p>此参数还可以是下列特定值的其中一个:</p>
      <p><strong>On</strong>: 启用热键. 如果热键已经处于启用状态, 则不进行操作.</p>
      <p><strong>Off</strong>: 禁用热键. 如果热键已经处于禁用状态, 则不进行操作.</p>
      <p><strong>Toggle</strong>: 设置热键到相反的状态 (启用或禁用).</p>
      <p><strong>AltTab</strong> (和其他): 这些是在 <a href="../Hotkeys.htm#alttab">这里</a> 描述的特殊的 Alt-Tab 热键动作.</p>
      <p>注意: <u>仅当不存在相应的标签时</u> 这些值才有特殊的含义. 例如, 如果标签 <code>On:</code> 存在并且此参数为单词 ON, 它被当成标签名称. 要启用或禁用这样的热键, 使用 <i>Options</i> 参数. <i>Label</i> 可以省略; 例如, <code>Hotkey Esc,, Off</code>.</p>
      <p>注意: <a href="#IfWin">当前的 IfWin 设置</a> 决定了 On/Off/Toggle 将操作热键的哪个 <a href="#variant">变体</a>.</p>      </td>
  </tr>
  <tr>
    <td>Options</td>
    <td><p>由下列零个或多个字母组成的字符串, 字母间可以用空格分隔. 例如: UseErrorLevel B0</p>
      <p><strong><a name="UseErrorLevel"></a>UseErrorLevel</strong>: 如果命令遇到问题, 此选项会跳过警告对话框, 设置 <a href="../misc/ErrorLevel.htm">ErrorLevel</a> 为 <a href="#ErrorLevel">下表</a> 中的一个代码, 然后让 <a href="../misc/Threads.htm">当前线程</a> 继续执行.</p>
      <p><strong>On</strong>: 如果热键当前是禁用的则启用它.</p>
      <p><strong>Off</strong>: 如果热键当前是启用的则禁用它. 此选项常用来创建一个初始状态为禁用的热键.</p>
      <p><strong>B</strong> 或 <strong>B0</strong>: 指定字母 B 将按照 <a href="_MaxThreadsBuffer.htm">#MaxThreadsBuffer</a> 描述的方法缓冲热键. 指定 B0 (B 后面跟着数字 0) 来禁用这种类型的缓冲.</p>
      <p><strong>Pn</strong>: 指定字母 P 后面跟着热键的 <a href="../misc/Threads.htm">线程优先级</a>. 如果创建热键时省略 P 选项, 则优先级被设置为 0.</p>
      <p><strong>Tn</strong>: 指定字母 T 后面跟着一个表示为此热键允许的线程数, 如同 <a href="_MaxThreadsPerHotkey.htm">#MaxThreadsPerHotkey</a> 中描述的那样. 例如: T5</p>
      <p>如果 <strong>B</strong> 和 <strong>T</strong> 选项中同时省略或省略了其中一个并且热键已经存在, 则这些设置不会改变. 但如果热键还不存在 -- 即使用当前命令创建热键时 -- 它们将使用最近使用的值. 例如, 将使用最靠近脚本结尾的 <a href="_MaxThreadsBuffer.htm">#MaxThreadsBuffer</a> 实例. 如果没有在脚本中使用 <a href="_MaxThreadsBuffer.htm">#MaxThreadsBuffer</a>, 则使用其默认设置 (OFF). 对于 <a href="_IfWinActive.htm">#IfWin</a> 也是这样: 除非脚本启动后执行过 "<a href="#IfWin">Hotkey IfWin</a>", 否则将对新创建的热键应用最近的实例.</p>
      <p>注意: <a href="#IfWin">当前的 IfWin 设置</a> 决定了 Hotkey 命令将操作热键的哪个 <a href="#variant">变体</a>. 如果此变体还不存在, 它将被创建.</p>      </td>
  </tr>
  <tr>
    <td>IfWinActive<br>
    IfWinExist</td>
    <td>(IfWin<strong>Not</strong>Active 和 IfWin<strong>Not</strong>Exist 也支持了). 这些子命令使此后创建的所有热键都是上下文相关的. 请参见 <a href="#IfWin">下面</a> 了解详情.</td>
  </tr>
  <tr>
    <td>WinTitle<br>
    WinText</td>
    <td><p>在这两个参数中, 任何变量引用如 %var% 在命令执行结束时被固定下来. 换句话说, 此后对这些变量内容的改变不会影响现有的热键.</p>
      <p>和 <a href="_IfWinActive.htm">#IfWinActive/Exist</a> 一样, <em>WinTitle</em> 和 <em>WinText</em> 为 <a href="SetTitleMatchMode.htm">SetTitleMatchMode</a> 和 <a href="DetectHiddenWindows.htm">DetectHiddenWindows</a> 使用在 <a href="../Scripts.htm#auto">自动执行段</a> 中的默认设置. 参见 <a href="_IfWinActive.htm">#IfWinActive/Exist</a> 了解详情. </p></td>
  </tr>
  <tr>
    <td>If, Expression</td>
    <td><span class="ver">[AHK_L 42]:</span> <a href="_If.htm">#If <i>Expression</i></a> 的副本. <i>Expression</i> 必须准确匹配 <b>现有的</b> <code>#If <i>expression</i></code>, 不包括 "<code>#If</code>" 或 "<code>#If,</code>". 当用于 Hotkey 命令时, "If" 后面的逗号是必须的. 尽管此命令不能创建新的表达式, 但它可以使用现有的表达式创建新的热键. 参见 <a href="_If.htm#ex4">#If example 4</a>.</td>
  </tr>
</table>

<h3 id="ErrorLevel">返回值</h3>
<p>只有在出现下列情况时 <a href="../misc/ErrorLevel.htm">ErrorLevel</a> 才会被改变: 1) 首个参数为 IfWin[Not]Active/Exist, 此时如果遇到问题返回值被设置为 1 否则为 0; 或 2) 在 <em>Options</em> 参数中使用了单词 UseErrorLevel .</p>
<table class="info">
  <tr>
    <th>错误</th>
    <th>描述</th>
  </tr>
  <tr>
    <td>1</td>
    <td><em>Label</em> 参数指定了一个不存在的标签名. </td>
  </tr>
  <tr>
    <td>2</td>
    <td><em>KeyName</em> 参数中指定了一个或多个当前键盘布局/语言无法识别或不支持的键.</td>
  </tr>
  <tr>
    <td>3</td>
    <td>不支持的前缀键. 例如, 使用鼠标滚轮作为热键的前缀, 如 <em>WheelDown &amp; Enter</em> 不被支持.</td>
  </tr>
  <tr>
    <td>4</td>
    <td><em>KeyName</em> 参数不适合用于 <a href="../Hotkeys.htm#alttab">AltTab 或 ShiftAltTab </a> 功能. 这种情况要求热键为两个键的组合. 例如: <em>RControl &amp; RShift::AltTab</em></td>
  </tr>
  <tr>
    <td>5</td>
    <td>命令尝试修改一个不存在的热键.</td>
  </tr>
  <tr>
    <td>6</td>
    <td>命令尝试修改一个现有热键的不存在的 <a href="#variant">变体</a>. 要解决此问题, 使用 "<a href="#IfWin">Hotkey IfWin</a>" 设置匹配那些需修改的热键变体的标准.</td>
  </tr>
  <tr>
    <td>50</td>
    <td>Windows 95/98/Me: 命令成功执行但操作系统拒绝激活此热键. 这种情况通常由于此热键被其他脚本或应用程序 (或 OS 自身) "在使用中" 所引起的. 这种情况只发生在 Windows 95/98/Me, 因为在其他操作系统中程序将采用 <a href="_InstallKeybdHook.htm">键盘钩子</a> 来 <a href="../misc/Override.htm">覆盖</a> 这个优先决定权.</td>
  </tr>
  <tr>
    <td>51</td>
    <td>Windows 95/98/Me: 命令成功执行但 Windows 95/98/Me 不支持此热键. 例如, 鼠标热键和前缀热键如 "a &amp; b" 不被支持.</td>
  </tr>
  <tr>
    <td>98</td>
    <td>如果创建了此热键将超过每脚本 1000 个热键的限制 (不过, 每个热键的 <a href="#variant">变体</a> 数目不受限制, 并且对于 <a href="../Hotstrings.htm">热字串</a> 的数目也没有限制).</td>
  </tr>
  <tr>
    <td>99</td>
    <td>内存不足. 这种情况极少, 通常仅在操作系统变得不稳定时才会发生.</td>
  </tr>
</table>
<p><br>
提示: 使用 UseErrorLevel 选项可以检查一个热键变体是否存在. 例如:</p>
<pre>Hotkey, ^!p,, UseErrorLevel
if ErrorLevel in 5,6
    MsgBox The hotkey does not exist or it has no variant for the current IfWin criteria.</pre>
<h3>备注</h3>
<p>如果是需要根据活动窗口的类型自动禁用选择的热键或热字串, 使用 <em>Hotkey, ^!c, Off</em> 通常不如 <a href="_IfWinActive.htm">#IfWinActive/Exist</a> (或它们的动态副本 "Hotkey IfWinActive/Exist" <a href="#IfWin">below</a>) 来的方便.</p>
<p>通过 <a href="../Hotkeys.htm">双冒号</a> 创建热键比使用 Hotkey 命令执行的更好因为在脚本启动时它们会被批量的启用 (而非一个一个地启用). 因此, 最好使用此命令创建那些在脚本开始运行后才知道键名的热键. 一种这样的情况是通过 <a href="IniRead.htm">INI 文件</a> 为热键配置多个不同的动作.</p>
<p>一个给定的标签可以是多个热键的目标. 如果一个热键调用了标签, 您可以通过检查内置变量 <a href="../Variables.htm#ThisHotkey">A_ThisHotkey</a> 来确定是哪个热键.</p>
<p>如果脚本是 <a href="Suspend.htm">挂起的</a>, 新增加/启用的热键也将是挂起的, 直到挂起状态被关闭 (除非它们像 <a href="Suspend.htm">Suspend</a> 命令中描述的那样被免除了).</p>
<p>由此命令做出的改变使得 <a href="_InstallKeybdHook.htm">键盘</a> 和/或 <a href="_InstallMouseHook.htm">鼠标</a> 钩子被安装或移除是正常的.</p>
<p>尽管 Hotkey 命令不能直接启用或禁用脚本中不是它创建的热键, 但在大多数情况下它可以通过创建或启用相同的热键来 <a href="../misc/Override.htm">覆盖</a> 它们. 这样是否有效取决于下列因素: 1) 在其他脚本中需要被覆盖的热键是否为 <a href="ListHotkeys.htm">钩子热键</a> (非钩子热键总是可以成功覆盖除非在 Win9x 系统中); 2) 最近启动的热键通常优先于其他脚本中的热键 (因此, 因此如果想要覆盖其他脚本的脚本是最近启动的, 覆盖总是会成功); 3) 此热键的启用或创建是否会重新激活 <a href="_InstallKeybdHook.htm">键盘</a> 或 <a href="_InstallMouseHook.htm">鼠标</a> 钩子 (如果是, 覆盖将总是成功).</p>
<p>每当脚本含有至少一个热键, 它会变成持续运行的, 这意味着需要使用 <a href="ExitApp.htm">ExitApp</a> 而不是 Exit 来终止它. 同时热键脚本自动为 <a href="_SingleInstance.htm">#SingleInstance</a> 的单实例属性除非指定了 <em>#SingleInstance Off</em>.</p>
<h3 id="IfWin">关于 <em>Hotkey, IfWinXX [, WinTitle, WinText]</em> 的备注</h3>
<p>"Hotkey IfWin" 命令允许在脚本运行时创建或修改上下文相关的 <a href="../Hotkeys.htm">热键</a> (与之相比, <a href="_IfWinActive.htm">#IfWinActive/Exist</a> 指令是由位置决定的并且在脚本启动时生效). 例如:</p>
<pre>Hotkey, IfWinActive, ahk_class Notepad
Hotkey, ^!e, MyLabel  <em>; 创建一个仅在记事本中有效的热键.</em></pre>
<p>使用 "Hotkey IfWin" 可以把所有后续创建或修改的 <a href="../Hotkeys.htm">热键</a> 都变成上下文相关的. 此外, 每个 IfWin 子命令是互斥的; 即只有最近的那个会起作用.</p>
<p>要关闭上下文相关性 (即让后续创建的热键对所有的窗口有效), 指定任一省略了 <em>WinTitle/Text</em> 参数的 IfWin 子命令. 例如: <em>Hotkey, IfWinActive</em></p>
<p>如果脚本中没有使用过 "Hotkey IfWin", 最近使用的 <a href="_IfWinActive.htm">#IfWin</a> (如果有的话) 将作用于 Hotkey 命令.</p>
<p>通过 IfWin 禁用鼠标或键盘热键后, 则热键会执行它原本的功能; 即如同这样的热键不存在那样被传递到活动窗口. 有两种情况例外: 1) Windows 95/98/Me: 按下一个被 IfWin 禁用的热键不会产生效果 (连原本的功能也失效); 和 2) 游戏杆热键: 尽管 IfWin 有效, 但它不会阻止其他程序探测到按钮的按下.</p>
<h3 id="variant">热键变体 (副本)</h3>
<p>只要每次定义时含有不同的 IfWin 条件, 一个特定的热键可以被创建多次. 这被称为 <em>热键变体</em>. 例如:</p>
<pre>Hotkey, IfWinActive, ahk_class Notepad
Hotkey, ^!c, MyLabelForNotepad
Hotkey, IfWinActive, ahk_class WordPadClass
Hotkey, ^!c, MyLabelForWordPad
Hotkey, IfWinActive
Hotkey, ^!c, MyLabelForAllOtherWindows</pre>
<p>如果有多个热键变体符合触发条件, 仅触发最早创建的那个. 这种情况的例外是全局变体 (不带有 IfWin 条件的那个): 它的优先级总是最低, 仅当其他变体都不触发时它才会被触发.</p>
<p>创建副本热键时, <a href="../Hotkeys.htm#Symbols">修饰符</a> 例如 ^!+# 的顺序无关紧要. 例如, ^!c 等同于 !^c. 但是, 按键的拼写必须一致. 例如, <em>Esc</em> 与 <em>Escape </em> 在这种情况下是不一样的 (尽管大小写没有关系). 最后, 任何带有 <a href="../Hotkeys.htm#wildcard">通配符前缀 (*)</a> 的热键和不带通配符的完全不同; 例如, *F1 和 F1 将拥有各自的变体设置.</p>
<p>关于 IfWin 热键的更多信息, 参见 <a href="_IfWinActive.htm#gen">#IfWin 的一般说明</a>.</p>
<h3>相关</h3>
<p><a href="../Hotkeys.htm#symbols">Hotkey Symbols</a>, <a href="_IfWinActive.htm">#IfWinActive/Exist</a>, <a href="_MaxThreadsBuffer.htm">#MaxThreadsBuffer</a>, <a href="_MaxThreadsPerHotkey.htm">#MaxThreadsPerHotkey</a>, <a href="Suspend.htm">Suspend</a>, <a href="../Functions.htm#IsLabel">IsLabel()</a>, <a href="../misc/Threads.htm">Threads</a>, <a href="Thread.htm">Thread</a>, <a href="Critical.htm">Critical</a>, <a href="Gosub.htm">Gosub</a>, <a href="Return.htm">Return</a>, <a href="Menu.htm">Menu</a>, <a href="SetTimer.htm">SetTimer</a></p>
<h3>示例</h3>
<pre class="NoIndent">Hotkey, ^!z, MyLabel return MyLabel: MsgBox You pressed %A_ThisHotkey%. return

<em>; Other examples:</em>
Hotkey, RCtrl &amp; RShift, AltTab <em>; Makes RCtrl &amp; RShift operate like Alt-Tab.</em>
Hotkey, #c, On <em>; Re-enables the Win-C hotkey.</em>
Hotkey, $+#c, Off <em>; Disables the Shift-Win-C hotkey.</em>
Hotkey, ^!a, , T5 <em>; Changes the hotkey to allow 5 threads.</em>

Hotkey, IfWinActive, ahk_class Notepad Hotkey, ^!c, MyLabelForNotepad <em>; Creates Ctrl-Alt-C as a hotkey that works only in Notepad.</em></pre>

</body>
</html>
